<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>Porting to Python 3</title>
  </head>

  <body>
    <h1>Porting to Python 3</h1>

    <h2>Introduction</h2>

    <p>Twisted is currently being ported to work with Python 3.3. This
    document covers Twisted-specific issues in porting your code to Python
    3.</p>

    <h2>API Differences</h2>

    <h3>twisted.python.failure</h3>

    <p><code class="API" base="twisted.python.failure">Failure.trap</code>
    raises itself (i.e. a <code class="API"
    base="twisted.python.failure">Failure</code>) in Python 2. In Python 3,
    the wrapped exception will be re-raised.</p>

    <h2>Byte Strings and Text Strings</h2>

    <p>Several APIs which on Python 2 accepted or produced byte strings
    (instances of <code>str</code>, sometimes just called <em>bytes</em>) have
    changed to accept or produce text strings (instances of <code>str</code>,
    sometimes just called <em>text</em> or <em>unicode</em>) on Python 3.</p>

    <p>From <code>twisted.internet.address</code>, the <code>IPv4Address</code>
    and <code>IPv6Address</code> classes have had two attributes change from
    byte strings to text strings: <code>type</code> and <code>host</code>.</p>

    <p><code>twisted.python.log</code> has shifted significantly towards text
    strings from byte strings.  Logging events, particular those produced by a
    call like <code>msg("foo")</code>, must now be text strings.  Consequently,
    on Python 3, event dictionaries passed to log observes will contain text
    strings where they previously contained byte strings.</p>

    <p><code>twisted.python.runtime.platformType</code> and the return value
    from <code>twisted.python.runtime.Platform.getType</code> are now both text
    strings.</p>

    <p><code>twisted.python.filepath.FilePath</code> has <em>not</em> changed.
    It supports only byte strings.  This will probably require applications to
    update their usage of <code>FilePath</code>, at least to pass explicit byte
    string literals rather than "native" string literals (which are text on
    Python 3).</p>

    <p><code>reactor.addSystemEventTrigger</code> arguments that were
    previously byte strings are now native strings.</p>

    <p><code>twisted.names.dns</code> deals with strings with a wide range of
    meanings, often several for each DNS record type.  Most of these strings
    have remained as byte strings, which will probably require application
    updates (for the reason given in the <code>FilePath</code> section above).
    Some strings have changed to text strings, though.  Any string representing
    a human readable address (for
    example, <code>Record_A</code>'s <code>address</code> parameter) is now a
    text string.  Additionally, time-to-live (ttl) values given as strings must
    now be given as text strings.</p>

    <p><code>twisted.web.resource.IResource</code> continues to deal with URLs
    and all URL-derived values as byte strings.</p>

    <p><code>twisted.web.resource.ErrorPage</code> has several string attributes
    (<code>template</code>, <code>brief</code>, and <code>detail</code>) which
    were previously byte strings.  On Python 3 only, these must now be text
    strings.</p>

  </body>
</html>
